home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Internet Pratique
/
Internet Pratique 01.iso
/
pc
/
Mac
/
LOGICIELS
/
DOSSIERS
/
MACAST10
/
MACAST Documentation
/
Plugin Development
/
MACAST_BLR.h
next >
Wrap
Text File
|
1999-09-16
|
13KB
|
336 lines
/*
Base Layer Renderer Plug-in API
⌐1999, @soft
Description: The plugin API for MACAST base layer renderer plugins (embedded plugins).
Version: 1.2
Released: 9/16/99
Compatibility: MACAST 1.0
Version history:
Date Who Changes
------+------+------------------------------------------------------
091699 SKA Added an ability for alternate BLR displays. See
example BLR for usage instructions.
082399 SKA Added BLRSettings and BLRListen, and Broadcast
callback. All BLRs should be recompiled.
071599 SKA Added BLRKeyDown call and removed BLRIdle (you can
do idle processing inside BLRRender).
071199 SKA Changed a couple of calls, and commented MACAST call-
backs a little better.
061999 SKA Added GetSoundBuffer hook for direct access to sound
data
050199 SKA Added hooks for saving and reading plugin-specific
preferences (see maBLRSavePrefs hook)
042799 SKA Modified the API with developer suggestions.
042699 SKA Initial release
041299 SKA Started the work
SKA = Slava Karpenko
*/
#pragma once
#ifdef __cplusplus
extern "C" {
#endif
/************************************************************
ENUMS AND CONSTANTS
************************************************************/
#define BLR_API_VERSION 0x0110
#define plugBaseLayerRenderer FOUR_CHAR_CODE('BLR!')
/************************************************************
ERRORS & RETURN VALUES
************************************************************/
enum {
// Plugin return codes
errBLRNoErr = noErr,
errBLRTerminate = 666, // terminate the plugin
errBLRNoMemory, // terminate the plugin and display no memory alert
errBLRCustom // MACAST will call BLRError function and terminate your
// plugin if you request to.
};
/************************************************************
FUNCTION DEFINITIONS
************************************************************/
// Called when the plugin is initialized. You get the FSSpec to the plugin file
// (for opening resfork if you need to), and base layer size.
extern OSStatus BLRInitialize(FSSpecPtr inPlugin, Rect inRect, UInt32* ioRefcon);
// Called on termination. Plugin should dispose all buffers/structures it had and prepare
// the mind for ethernity.
extern OSStatus BLRTerminate(UInt32* ioRefcon);
// Called whenever user presses a key. Your BLR get this event all the time. You can process it or
// ignore it.
extern OSStatus BLRKeyDown(EventRecord* inEvent, UInt32* ioRefcon);
// Return copyrights strings to be displayed on plugin about. \r is acceptable, 3 lines max.
extern OSStatus BLRGetCopyright(StringPtr outCopyright, UInt32* ioRefcon);
// Main function, called periodically -- render base layer. You can use MA callbacks
// to obtain any necessary information.
// Note that inRect is most likely the same as given to you at init time. If user changes
// skin with different computer bounds, MACAST will terminate and re-init the plugin.
extern OSStatus BLRRender(GWorldPtr inRenderTarget, Rect inRect, UInt32* ioRefcon);
// This function is called when user clicks in layer that is controlled by your plugin.
// You should look at it and return either 'true' -- means you handled the click and
// MACAST should take no other actions. If you don't handle clicks or don't handle click
// in that point, return false and MACAST will rotate through BLR plugins. inClick is in
// local coordinates relative to inRect given at init time.
extern Boolean BLRClick(Point inClick, UInt32* ioRefcon);
// This function called if you return errBLRCustom. You should copy the error string
// and errNum (optionally) and return whether the error is fatal or not. If this function
// returns true, MACAST terminates your plugin, otherwise continues execution.
extern Boolean BLRError(StringPtr outErrString, OSStatus* outErrNum);
// If you define this function in your gPlugInfo, MACAST will add a corresponding item into
// 'Settings' submenu of plugins menu and will call this function when user chooses it.
// You can display settings dialog, and do whatever you want.
extern OSStatus BLRSettings(UInt32* ioRefcon);
// If you define this in your gPlugInfo, MACAST will send you all internal messages defined in
// MACAST_Events.h. This area is highly undocumented, so it's suggested that if you listen to events
// for some purpose, avoid translating them via Broadcast hook.
extern OSStatus BLRListen(SInt32 inMessage, void* inData, UInt32* ioRefcon);
// If your BLR has more than one display mode, it is advisable to return total number of display
// modes here thus allowing users to switch between them via 'Switch Mode' drawer button. Call
// ma->GetMode() in BLRRender to find out in what mode we currently is.
// If you do not define BLRGetModes, MACAST assumes BLR has only one mode.
extern SInt16 BLRGetModes(void);
// If your BLR has more than one display mode, this function will be called when user switches modes --
// in attempt to get a mode 'name' to be displayed. if you don't want to display a name for current mode
// return empty string for outName. If you don't want to display a name for all modes, don't define this
// function.
extern OSStatus BLRGetModeName(SInt16 inMode, StringPtr outName);
/************************************************************
TYPEDEFS AND STRUCTS
************************************************************/
// ÑPlugin callbacks
typedef OSStatus (*blrInitProcPtr)(FSSpecPtr, Rect, UInt32*);
typedef OSStatus (*blrGenericProcPtr)(UInt32*);
typedef OSStatus (*blrKeyDownProcPtr)(EventRecord*, UInt32*);
typedef OSStatus (*blrGetCopyrightProcPtr)(StringPtr, UInt32*);
typedef OSStatus (*blrRenderProcPtr)(GWorldPtr, Rect, UInt32*);
typedef Boolean (*blrClickProcPtr)(Point, UInt32*);
typedef Boolean (*blrErrorProcPtr)(StringPtr, OSStatus*);
typedef OSStatus (*blrListenProcPtr)(SInt32, void*, UInt32*);
typedef SInt16 (*blrGetModesProcPtr)(void);
typedef OSStatus (*blrGetModeNameProcPtr)(SInt16 inMode, StringPtr outName);
// ÑMACAST Callbacks
// You heavily rely on these to deliver good rendering.
typedef void (*maBLRGetValuesArray)(UInt8** outArray, UInt16* outArraySize);
// Get an array of pre-computed values for frequences.
// Every value represents one frequency, and can be in range #0-232.
// Input:
// none
// Output:
// outArray = pointer to values array
// outArraySize = size of the array
// Returns:
// nothing
typedef void (*maBLRGetFFTArray)(double** outFFT, UInt16* outFFTSize);
// Get FFT array. First half of the array are real parts, second - imaginary.
// Input:
// none
// Output:
// outFFT = pointer to raw fft array (or nil, if not available)
// outBufferSize = size of the array
// Returns:
// nothing
typedef void (*maBLRGetSoundBuffer)(Ptr* outSoundBuffer, UInt16* outBufferSize);
// Get current sound buffer.
// Input:
// none
// Output:
// outSoundBuffer = pointer to sound buffer being played (or nil, if no track is playing)
// outBufferSize = size of the buffer, in bytes
// Returns:
// nothing
typedef void (*maBLRGetStatus)(UInt32* outTimer, UInt32* outStatus);
// Get status of thge player (timer, states of repeat, random, sleep etc).
// Input:
// none
// Output:
// outTimer = timer, in seconds
// outStatus = flags field containing stat* constants.
// (for example, to check if Random mode is set, check for (outStatus & statRandom))
// Returns:
// nothing
// Status codes
enum {
statRandom = (1L << 0),
statSleep = (1L << 1),
statRepeat = (1L << 2),
statRepeat1 = (1L << 3),
statPlaying = (1L << 4),
statPaused = (1L << 5),
statStopped = (1L << 6)
};
typedef void (*maBLRGetGWorld)(GWorldPtr* outGWorld, Rect* outRect);
// Get a GWorld with digits or status lights.
// Input:
// none
// Output:
// outGWorld = pointer to a GWorld containing requested data
// outRect = rectange defining bounds of GWorld
// Returns:
// nothing
typedef void (*maBLRDarkenWorkArea)(void);
// Darken work area (to simulate 'something-on-top' effect).
// Input:
// none
// Output:
// none
// Returns:
// nothing
typedef void (*maBLRSetStdColors)(void);
// Set skin-defined colors on current port.
// It's your responsibility to return original colors later.
// Input:
// none
// Output:
// none
// Returns:
// nothing
typedef OSStatus (*maBLRSavePrefs)(OSType inAuthorID, OSType inPluginID, Ptr inBuffer, UInt16 inSize);
// Save plugin-specific preferences in MACAST Data file located in System Folder.
// Input:
// inAuthorID = authorID of plugin
// inPluginID = pluginID of plugin
// inBuffer = pointer to buffer containing preferences chunk to be saved
// inSize = size of buffer to be saved
// Output:
// none
// Returns:
// noErr = preferences saved successfully.
// memFullErr = an unknown, probably memory-related error has occurred.
typedef OSStatus (*maBLRReadPrefs)(OSType inAuthorID, OSType inPluginID, Ptr inBuffer, UInt16* ioSize);
// Read plugin-specific preferences you have saved before with SavePrefs hook.
// Input:
// inAuthorID = authorID of plugin
// inPluginID = pluginID of plugin
// inBuffer = pointer to pre-allocated buffer to store preferences
// ioSize = size of allocated buffer
// Output:
// ioSize = actual size of preferences
// Returns:
// noErr = preferences read successfully.
// resNotFound = unable to find such preferences chunk
// memFullErr = size of preferences chunk exceeds size of allocated buffer
// (ioSize contains size of preferences chunk)
typedef void (*maBLRBroadcast)(SInt32 inMessage, void* inData);
// Broadcast MACAST system message to its subsystems. Don't call this unless you know
// what you're doing.
// Input:
// inMessage = message id to be broadcasted
// inData = data to be broadcasted, or nil
// Output:
// none
// Returns:
// nothing
typedef SInt16 (*maBLRGetMode)(void);
// Returns the current mode the MACAST is in. This value is between 0 and numModes-1 returned from
// BLRGetModes call, or always 0 if you have not defined BLRGetModes.
// Input:
// none
// Output:
// none
// Returns:
// SInt16 = current mode number (0 <= x <= numModes-1)
// Various structures
#pragma options align=power
// This is the structure for MACAST callbacks.
typedef struct {
// Getters
maBLRGetValuesArray GetValues;
maBLRGetFFTArray GetFFT;
maBLRGetStatus GetStatus;
// Utility functions
maBLRDarkenWorkArea DarkenWorkArea;
maBLRSetStdColors SetStdColors;
maBLRGetGWorld GetTimerDigits;
maBLRGetGWorld GetStatusLights;
// Preferences
maBLRSavePrefs SavePrefs;
maBLRReadPrefs ReadPrefs;
maBLRGetSoundBuffer GetSoundBuffer;
// New for 1.1
maBLRBroadcast Broadcast;
// New for 1.2
maBLRGetMode GetMode;
} BLRCallbacks, *BLRCallbacksPtr;
// Main structure for the plugin. Main entry point for the PEF fragment should point to
// a global variable of this type.
typedef struct {
UInt16 api; // API used. Should always contain BLR_API_VERSION
OSType type; // Plugin type. Should be plugBaseLayerRenderer.
OSType authorID; // Author ID should be registered with @soft to prevent
// incompatibilities. mailto:devsupport@at-soft.net
OSType pluginID; // Plugin ID can be anything the author wishes. It is
// used among with author id to store user preferred
// base layer renderer plugin etc.
UInt32 flags; // Plugin flags (reserved)
// function prototypes
blrInitProcPtr initProc;
blrGenericProcPtr terminateProc;
blrGetCopyrightProcPtr getCopyrightProc;
blrRenderProcPtr renderProc;
blrClickProcPtr clickProc;
blrKeyDownProcPtr keyDownProc; // set to nil if you don't want keydowns
blrErrorProcPtr errorProc;
blrGenericProcPtr settingsProc; // set to nil if you don't have settings
blrListenProcPtr listenProc; // set to nil if you don't want to receive internal engine messages
blrGetModesProcPtr getModesProc; // set to nil if you only have one display mode
blrGetModeNameProcPtr getModeNameProc; // set to nil if you dont use display mode names
// Set these to nil. They are reserved for future expansion so BLRs don't have to be recompiled.
blrGenericProcPtr reservedProc1;
blrGenericProcPtr reservedProc2;
// Special APIs (Set to nil, MACAST will set it to the right value)
BLRCallbacksPtr ma;
} BLRInfoBlock, *BLRInfoPtr;
#pragma options align=reset
// useful macros to quickly set headers/footers of VPInfoBlock
#define BLR_INFOBLOCK_HEADER(a,b) BLR_API_VERSION, plugBaseLayerRenderer, a, b, nil
#define BLR_INFOBLOCK_FOOTER nil, nil, nil
#ifdef __cplusplus
}
#endif